<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>SoundGet</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>SoundGet</h1>

<p>Retrieves various settings from a sound device (master mute, master volume, etc.)</p>

<pre class="Syntax">SoundGet, OutputVar [, ComponentType, ControlType, DeviceNumber]</pre>
<h3>Parameters</h3>
<dl>

  <dt>OutputVar</dt>
  <dd><p>The name of the variable in which to store the retrieved setting, which is either a floating point number between 0 and 100 (inclusive) or the word ON or OFF (used only for <em>ControlTypes</em> ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, and BASSBOOST). The variable will be made blank if there was a problem retrieving the setting. The format of the floating point number, such as its decimal places, is determined by <a href="SetFormat.htm">SetFormat</a>.</p></dd>

  <dt>ComponentType</dt>
  <dd><p>If omitted or blank, it defaults to the word MASTER. Otherwise, it can be one of the following words: MASTER (synonymous with  SPEAKERS), DIGITAL, LINE, MICROPHONE, SYNTH, CD, TELEPHONE, PCSPEAKER, WAVE, AUX, ANALOG, HEADPHONES, or N/A. If the sound device lacks the specified <em>ComponentType</em>, ErrorLevel will indicate the problem.</p>
      <p>The component labeled Auxiliary in some mixers might be accessible as ANALOG rather than AUX.</p>
    <p>If a device has more than one instance of <em>ComponentType</em> (two of type LINE, for example), usually the first contains the playback settings and the second contains the recording settings. To access an instance other than the first, append a colon and a number to this parameter. For example: <code>Analog:2</code> is the second instance of the analog component.</p></dd>

  <dt>ControlType</dt>
  <dd><p>If omitted or blank, it defaults to VOLUME. Otherwise, it can be one of the following words: VOLUME (or VOL), ONOFF, MUTE, MONO, LOUDNESS, STEREOENH, BASSBOOST, PAN, QSOUNDPAN, BASS, TREBLE, EQUALIZER, or the number of a valid control type (see <a href="SoundSet.htm#Ex">soundcard analysis script</a>). If the specified <em>ComponentType</em> lacks the specified <em>ControlType</em>, ErrorLevel will indicate the problem.</p>
    <p><strong>Note:</strong> sound devices usually support only VOLUME (or VOL) and MUTE, although others may be available depending on Windows and the sound device.</p></dd>

  <dt>DeviceNumber</dt>
  <dd><p>A number between 1 and the total number of supported devices. If this parameter is omitted, it defaults to 1 (the first sound device), or on Windows Vista or above, the system's default device for playback. This parameter can be an <a href="../Variables.htm#Expressions">expression</a>. The <a href="SoundSet.htm#Ex">soundcard analysis script</a> may help determine which number to use.</p></dd>

</dl>
<h3>ErrorLevel</h3>
<p><span class="ver">[v1.1.04+]</span> This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 0 if the command succeeded. Otherwise, it is set to one of the following phrases:</p>
<table class="info" style="width:436px">
  <tr>
    <td width="426">Invalid Control Type or Component Type</td>
  </tr>
  <tr>
    <td>Can't Open Specified Mixer</td>
  </tr>
  <tr>
    <td>Mixer Doesn't Support This Component Type</td>
  </tr>
  <tr>
    <td>Mixer Doesn't Have That Many of That Component Type</td>
  </tr>
  <tr>
    <td>Component Doesn't Support This Control Type</td>
  </tr>
  <tr>
    <td>Can't Get Current Setting</td>
  </tr>
</table>
<h3>Remarks</h3>
<p>Support for Windows Vista and later was added in v1.1.10.</p>
<p>To discover the capabilities of the sound devices (mixers) installed on the system -- such as the available component types and control types -- run the <a href="SoundSet.htm#Ex">soundcard analysis script</a>.</p>
<p>For more functionality and finer grained control over audio, consider using the <a href="http://www.autohotkey.com/board/topic/21984-vista-audio-control-functions/">VA library</a>.</p>
<p>Use <a href="SoundSet.htm">SoundSet</a> to change a setting.</p>
<h3>Related</h3>
<p><a href="SoundSet.htm">SoundSet</a>, <a href="SoundGetWaveVolume.htm">SoundGetWaveVolume</a>, <a href="SoundSetWaveVolume.htm">SoundSetWaveVolume</a>, <a href="SoundPlay.htm">SoundPlay</a></p>
<h3>Examples</h3>
<pre class="NoIndent">SoundGet, master_volume
MsgBox, Master volume is %master_volume% percent.

SoundGet, master_mute, , mute
MsgBox, Master Mute is currently %master_mute%.

SoundGet, bass_level, Master, bass
if ErrorLevel
    MsgBox, Error Description: %ErrorLevel%
else
    MsgBox, The BASS level for MASTER is %bass_level% percent.

SoundGet, microphone_mute, Microphone, mute
if microphone_mute = Off
    MsgBox, The microphone is not muted.</pre>

</body>
</html>
